Mol Inspector Help

Please note this is for version β.0.0, and that if this page is acceseed from the program, it may not have been updated, please visit kyll.dk/MolInspector/Manual/Beta-0-0 for the newest version the β.0.0 manual.

1 - General User-Interface

Kylles Mol-Inspector's user interface is divided into four areas, as seen below. 1) The Molecule List is located on the left side of the UI and shows a list of compounds loaded in. 2) The Property Inspector located on the right of the UI shows the list of properties for the selection molecule, atom, or bond. 3) The Molecule View, shown centrally, is where the molecular structure is drawn, together with any visualization chosen, and 4) The Ribbon Controls located at the top, is where options for loading compounds, visualization of properties together with export options are found

1.1 - The Molecule List

The molecule list shows a list of the compounds loaded in. Each compounds is shown with an index number, a name, is one is available in the file, or chemical formula if no name is available, and the number of errors, which occured when loaded in.

A compound in red, indicates that the compound could not be loaded in correctly, or a structure could not be generated for it. This is often due to the kekulize error, described below. A compound in bold letters, indicates that that compound is selected.

To select a compound, simply click on it.

1.2 - The Property Inspector

The property inspector shows the properties of whatever is selected. If you click on an atom, it will show the properties of the selected atom, and the same goes for bonds. If you want to show the properties of the molecule as a whole, the benzene icon in the top right allows that, and the "!" next to it will show a list of errors that occured when loading in that molecule.

Each property is shown with a icon indicating the type, integer,float,categorical or boolan. The name of the property in question and the value of said property. The properties are divided into some collapsable groups to make it easier to look through them.

Clicking on a feature will generate a plot and legend appropriate for said feature. Be aware, if a feature is note loaded in correctly, it may show up as "false" or "0" in the inspector, clcik on the "!" to see the errors, which will tell if there is any feature not loaded in.

1.3 - The Molecule Viewer

Within the molecular viewer, you'll find a drawn structure of the compound selected in The Molecule List. by clicking on any of the atoms or bonds in molecular structure, the properties of those bonds will be shown in Property Inspector you can pan using the mouse and zoom using the scroll-wheel on the mouse.

The view in the molecular viewer can be changed in the "view" tab of The Ribbon Controls at the top, and vizualization of properties can be made by clicking on any atom/bond property in the Property Inspector.

When you hover over an atom or bond, a circle is shown indicating what you will select, sometimes, this may be too large if there are too many atoms in the compound. You can change the selection size in the "view" tab of The Ribbon Controls.

Here an example of 15px and 5px atom selection size

Note that sometimes is "Sanitization" is on, molecules may not be drawn, and giving and error, see Kekulization Error for more.

1.4 - The Ribbon Control

The ribbon control contains most options in the program, and is divided into 3 tabs, "Home", "View" and "Export". In the "Home" tab, shown below, you'll find options for loading in a compound, which is described further in the How To Load Molecules section, in addiction to that, you'll find the option to change the GUI theme as well as acess this about and help page (not the help page, is acessed offline, you can go to the website to reach the newest version).

In the "View" tab you'll find options to customize the look of the molecular structure as well as the vizualizations, which is described in detail in the Making Plots section.

And lastly in the "Export" tab you are able to export either the properties found by the program or the figures and representations made, which you can lean more on in the Export section of this manual.

2 - How To Load Molecules

You can either load in a single compound as a SMILES, by entering the SMILES string in the textbox in the load-section of the home tab in The Ribbon Controls, and pressing the "Load File" button. Alternative multiple molecules can be loaded in from an .SDF file, where the path to the SDF file can either be entered in the textbox or found by opening a dialog using the "..." button, in either case, followed by pressing the "Load File" button.

2.1 - Sanitization

The sanitize option present, determins wehter or not to perform RDKits sanitization prosees (click here) which, in short, calculates some properties and tries to ensure compounds are "reasonable". While this can be usefull in some cases, if a compound cannot be sanitized, (especially fused rings, see Kekulization Error), having this option on may prevent the structure to be drawn.

2.2 - SDF Properties

When loading in an SDF file, there is a set of choices for how to treat atomic and bond properties in that SDF file.

In SDF files, there's not a readily available way to incorporate custom atomic / bond properties, but only comments/properties for the whole molecule. To circumvent this, atomic / bond properties are written as a list in the order of the bond/atom indices as a molecular properties. Further, comments/atomic properties are not typed, so are loaded in as strings. In order to keep track of what is atomic/molecular and bond properties and their type, RDKit uses a naming scheme in the style [atom/bond].[type].[name], such as seen in the SDF-file below for ethanol.

If "Use RDKIt Prop" is checked then, rdkit will be used to load in properties of this general naming scheme.

The two other methods, "Guess Atom Prop" and "Guess Bond Prop" are made to load in atomic or bond properties not following any specific naming scheme. They work rather simply by checking if, for a given property, if the string when split using the separators " ", "\n", "\r" or "\t" contains the same number of items as the number of atom/bonds, and if so, assumes the property to be an atomic or bond property.

If there are an equal number of atoms and bonds, it will add properties as atomic properties, unless "Prioritize Bond Prop" is checked.

If "Use RDKit Prop" and "Guess Atom Prop" and/or "Guess Bond Prop" is checked, then properties following the naming scheme outlined before will be handled with RDKit, and any other property handled by the "Guess Atom/Bond Prop" method. If RDKit is unchecked but "Guess Atom Prop" and/or "Guess Bond Prop" is checked, then every feature will be handled by the "Guess Atom/Bond Prop" methods. Note however in these cases a temporary copy of the input SDF file will be created and loaded where RDKits property names are changed to start with "(RDKit)", to avoid RDKits' automatic handling of the features.

3 - Making Plots

In order to vizualize an atomic or bond property, simple left click on the name of that property in the Property Inspector, and a visuzlization for that type will be made.

3.1 - Customizing Molecules

You may want to change the molecular structure representation used for the vizualization. If you want to change the color scheme used for atoms, currently you'll have to select a different UI theme in the "Home" tab of The Ribbon Controls, such as having dark or light theme.

Under the "View" tab of The Ribbon Controls, you can change the "size" used for the compound, the effect of which can be seen below.

In the view tab, you can also toggle wether or not to show the indicies of atoms.

If the molecule is loaded in from an .sdf file, with a given conformation, you can either force a 2D view, or show the compound in the 3D conformation from the file.

3.2 - Boolean Plots

If you click on an atomic/bond feature of boolean type, a vizualization is made where circles are drawn for each atom/bond where the feature is "true". The color and size of the circles can be set on the "plot" section under the "view" tab.

3.3 - Categorical Plots

If you click on an atomic/bond property of a categorical type, a plot will be made with different colors used for different options in that category. The size of the circles used is set with same option as for boolean plots, and the color scheme can be set in the dropdown box "Category Theme"

3.4 - Numberical Plots

Plots for integer value, or for floating point values, are per default shown as a contour plot, which can be customized, both in the color scheme used, using the "Float/Int Theme" to select the color scheme.

The number of levels to use for the contour can be selected in the "contour" section of the view-tab wher the opacity and the sigma, the effect of which can be seen below (sigma = 25 & 10), can also be selected.

If "Plot Contour" is off, a set of circles will be drawn instead with color matching the value of the bond/atoms property.

4 - Export

In the "export" tab in The Ribbon Controls, you'll find options to both export the read properties as well as the figures created.

4.1 - Exporting Properties

If you want to export the properties calculated / found, this can be done under "export as csv" in the export tab of the ribbon control. A series of different options are available to control what will be exported.

The "Only Selected Mol" option, determins if its only the molecule currently selected properties should be exported from or if its all molecules currently loaded. Under The "What To Export" you can select the item to export, this may be "Atomic Properties", "Bond Properties", "Molecular Properties", "Errors" or if "All Properties" is selected, then all of the previously mentioned ones. If "In Inspector" is selected only the properties shown in the property inspector will be show.

The .CSV file will contain 8 different rows, the first "Compound Name" and "Compound SMILE" provide identifiers for the compound the properties are made for. The "Property Type" indicates what the property is for, either atomic, bond or molecular property, or error, and the "Property Name" is the name of that property, "Variable Type" takes the data-type of the property, either as Int (for integer), Float, Bool (For Boolean) or Object (For categorical items or strings). The "Property Origin" Field indicates is the property is calculated by RDKit/Mol-inspector or if its from a the file. "Atom/Bond ID" indicates the index of the atom or bond which the property is for, if its a molecular property or error this always be set as 0, and lastly "Property Value" is the value of the property in question.

Example .CSV for Ethanol (No Errors or SDF Properties)

4.2 - Exporting Figures

Figures can be exported under the "export" tab in the ribbon control, there are only two options present for this, one is "Include Legend" which determins wether or not the legend should be included in the exported image, and two "File Type" which determins which file-type to export as, this can either be ".svg", ".png" or ".pdf".

Note that currently there is a slight issue in the figure export, where the size of the exported image is quite a bit larger than it should be, with a lot of empty space, this is a bug, which will hopefully be fixed soon.

5 - Notes

5.1 - Kekulization Error

An error which a user is likely to encounter often is one stating certain atom could not be Kekulized, and if sanitization is on, this may lead to the molecule not being showed, and this error therefore deserves some explanation.

What is kekulization ? Its the processes of assigning bond order to the compound, and in the case of aromatic compounds, its the assignment of alternating double-single bond pattern to the aromatic system.

An error in kekulization, is, in most cases only an issue for drawing the compound, and is not and issue with the molecule nor SDF file itself, turning sanitization off when loading in the compound, should allow the compound to be drawn even if kekulization fails, but not you'll notice aromatic bonds, in molecule where kekulization failed, are drawn with a dotted secound line to indicate aromaticity instead of alternating double-single bonds.

Further, it should be mentioned that if kekulization fails, creation of inchi and inchikey notation for the compound is likely to fail as well, due to how they are created.

Why and when do kekulization fail ? In almost every case, its an issue with fused aromatic systems, which RDKit is not always able to correctly kekulize, if the system as a whole is aromatic but individual rings are not.

5.2 - Similar Tools

Mol-Inspector is made primarily to debug and troubleshoot SDF files, it is however not the only tool to debug chemical file formats and type. I'd like to here also mention Hack-A-Mol which allows manipulation of SDF XYZ and other file format and see how they effect the loaded compound, which is very usefull.

The other one worth mentioning here is SMARTS.plus which provides very easily understandable vizualiations of SMARTS queries.